Proposed documentation for proposed Model element #39710

zachernuk · 2025-05-27T18:21:01Z

Description

This PR adds API documentation about the proposed HTML Model element, a browser-native feature for the in-line display of 3D content. It includes illustrations of some core concepts like perspective, lighting and appropriate file formats.

Motivation

The Model element is a totally new web feature and it'll be exceptionally difficult to add documentation in a piecemeal fashion. I'm hoping that this covers the core concepts enough to author new pages from, and matches the MDN house style well enough that other folks can improve them to the point that they are real!

Additional details

I am submitting provisional documentation for the HTML model element, a feature that is the major source of discussion in the W3C Immersive Web CG (https://github.com/immersive-web/model-element/ )
and which is available as a feature preview in visionOS 2.4. I am an editor of the specification and have been facilitating the discussion around it.

While the specification doesn’t have a lot of detail, the API in visionOS is based on the consensus discussion in the CG, and is described in the Model Element explainer: (https://github.com/immersive-web/model-element/blob/main/explainer.md )

There is also a WebGL/WebXR-based interactive explainer demo available here:
https://immersive-web.github.io/model-element/explainer_demo.html

We also have public samples being contributed by multiple browser vendors in the model element samples repository.
https://immersive-web.github.io/model-element-samples/

We have previously submitted related additions to the WHATWG HTML specification as via an introductory issue and initial PR for the specification stub.
whatwg/html#10901
whatwg/html#11191

Related issues and pull requests

WHATWG/HTML

the Web Platform Tests repository

Initial Model element tests web-platform-tests/wpt#51667

HTML-ARIA

New in-line 3D HTML model element w3c/aria#2508

A full suite of the currently agreed-upon API and capability of the Model element, as discussed in the Immersive Web CG

rebuilt with the yarn builder so the lockfile should match upstream

Copied the yarn lockfile back to the upstream state

zachernuk · 2025-05-27T18:38:31Z

@mkeblx @LaszloGombos @cabanier Here's a run at the MDN docs! LMK if there's anything obviously outside of our discussions on it so far.

github-actions · 2025-05-27T20:00:07Z

Preview URLs (20 pages)

Flaws (1)

Note! 19 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/model_role

External URLs (13)

URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxCenter
Title: HTMLModelElement: boundingBoxCenter property

https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxExtents
Title: HTMLModelElement: boundingBoxExtents property

https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLModelElement/environmentMap
Title: HTMLModelElement: environmentMap property

https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLModelElement/playbackRate
Title: HTMLModelElement: playbackRate property

https://en.wikipedia.org/wiki/Double-precision_floating-point_format (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element

https://en.wikipedia.org/wiki/Cartesian_coordinate_system (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Identity_matrix (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/OpenEXR (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/RGBE_image_format (1 time) (Note! This may be a new URL 👀)
https://openusd.org/release/spec_usdz.html (1 time) (Note! This may be a new URL 👀)
https://www.khronos.org/gltf/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-05-29 20:52:58)

Updated casing on some attribute/property names, update to the richer paths on things like Content categories

Josh-Cena

Some random drive-by reviews. Not comprehensive in any way, but they indicate some common problems that would need to be fixed throughout.

Also we need browser compat data for this. It should be shipping in at least one browser to be documented.

Josh-Cena · 2025-05-28T03:29:16Z

yarn.lock

@@ -9836,4 +9836,4 @@ yoctocolors@^2.0.0:
 zwitch@^2.0.0, zwitch@^2.0.4:
  version "2.0.4"
  resolved "https://registry.yarnpkg.com/zwitch/-/zwitch-2.0.4.tgz#c827d4b0acb76fc3e685a4c6ec2902d51070e9d7"
-  integrity sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==
+  integrity sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==


Josh-Cena · 2025-05-28T03:29:51Z

files/en-us/web/html/reference/elements/model/index.md

+
+- While it provides benefits for all devices and User Agents, the `<model>` element has particular value on platforms with stereoscopic and/or head-tracking capabilities, such as Head-Mounted Displays (HMDs). It can be used as declarative alternative to the WebXR API to provide spatial content.
+
+## Object fit


These should be H3 headings. The H2 sequence is exactly those defined in the page template

Josh-Cena · 2025-05-28T03:30:33Z

files/en-us/web/api/htmlmodelelement/width/index.md

+A model's contents is set to automatically fit within the portal's
+`width` and `height` dimensions at the moment that the `ready` Promise


General comment: please don't wrap your prose like this. Either wrap at each period, or don't wrap and just have paragraph breaks

Josh-Cena · 2025-05-28T03:30:53Z

files/en-us/web/api/htmlmodelelement/stagemode/index.md

+
+Setting the `stagemode` to `orbit` immediately has these consequences for the model element's `entityTransform`:
+
+- Transform is <strong>`orbit-fit`</strong>:


Use Markdown

Josh-Cena · 2025-05-28T03:31:04Z

files/en-us/web/api/htmlmodelelement/ready/index.md

+This example demonstrates how to confirm that both a model's scene and environment map resources are ready for rendering, and how to gracefully address failed parsing:
+
+```js
+let modelElem = document.getElementById("model");


Use const where possible

Josh-Cena · 2025-05-28T03:31:41Z

files/en-us/web/api/htmlmodelelement/environmentmapready/index.md

+
+## See also
+
+- [model.ready](/en-US/docs/Web/API/HTMLModelElement/ready)


Suggested change

- [model.ready](/en-US/docs/Web/API/HTMLModelElement/ready)

- [`HTMLModelElement.ready`](/en-US/docs/Web/API/HTMLModelElement/ready)

Josh-Cena · 2025-05-28T03:32:03Z

files/en-us/web/api/htmlmodelelement/entitytransform/index.md

+
+## See also
+
+- {{domxref("HTMLModelElement")}}: Interface used to define the `HTMLModelElement.entityTransform` property


Suggested change

- {{domxref("HTMLModelElement")}}: Interface used to define the `HTMLModelElement.entityTransform` property

- {{domxref("HTMLModelElement")}}

We don't add explanatory text for see also

Remove arbitrary wrapping, Change `let` to `const`, Fixed the 'ARIA role' reference urls, Demoted some headings to be in line with MDN standards, Applied markdown-based bolding

…into model-element

zachernuk added 3 commits May 27, 2025 10:51

Initial suite of files to describe the Model element

741e4f0

A full suite of the currently agreed-upon API and capability of the Model element, as discussed in the Immersive Web CG

Update yarn.lock

6562d17

rebuilt with the yarn builder so the lockfile should match upstream

Update yarn.lock

0634081

Copied the yarn lockfile back to the upstream state

zachernuk requested review from mdn-bot and a team as code owners May 27, 2025 18:21

zachernuk requested review from estelle and sideshowbarker and removed request for a team May 27, 2025 18:21

github-actions bot added Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs system [PR only] Infrastructure and configuration for the project size/xl [PR only] >1000 LoC changed labels May 27, 2025

zachernuk and others added 2 commits May 27, 2025 13:49

Fix from GH-actions feedback

09245bf

Updated casing on some attribute/property names, update to the richer paths on things like Content categories

Merge branch 'main' into model-element

5e1c9f7

Josh-Cena reviewed May 28, 2025

View reviewed changes

zachernuk added 2 commits May 27, 2025 23:33

Update with @Josh-Cena 's feedback

6764f3b

Remove arbitrary wrapping, Change `let` to `const`, Fixed the 'ARIA role' reference urls, Demoted some headings to be in line with MDN standards, Applied markdown-based bolding

Merge branch 'model-element' of https://github.com/zachernuk/content …

29aea0a

…into model-element

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Proposed documentation for proposed Model element #39710

Proposed documentation for proposed Model element #39710

zachernuk commented May 27, 2025 •

edited

Loading

Uh oh!

zachernuk commented May 27, 2025

Uh oh!

github-actions bot commented May 27, 2025 •

edited

Loading

Uh oh!

Josh-Cena left a comment

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Josh-Cena May 28, 2025

Uh oh!

Uh oh!


		- While it provides benefits for all devices and User Agents, the `<model>` element has particular value on platforms with stereoscopic and/or head-tracking capabilities, such as Head-Mounted Displays (HMDs). It can be used as declarative alternative to the WebXR API to provide spatial content.

		## Object fit

		A model's contents is set to automatically fit within the portal's
		`width` and `height` dimensions at the moment that the `ready` Promise


		Setting the `stagemode` to `orbit` immediately has these consequences for the model element's `entityTransform`:

		- Transform is <strong>`orbit-fit`</strong>:


		## See also

		- [model.ready](/en-US/docs/Web/API/HTMLModelElement/ready)

	- [model.ready](/en-US/docs/Web/API/HTMLModelElement/ready)
	- [`HTMLModelElement.ready`](/en-US/docs/Web/API/HTMLModelElement/ready)


		## See also

		- {{domxref("HTMLModelElement")}}: Interface used to define the `HTMLModelElement.entityTransform` property

	- {{domxref("HTMLModelElement")}}: Interface used to define the `HTMLModelElement.entityTransform` property
	- {{domxref("HTMLModelElement")}}

Proposed documentation for proposed Model element #39710

Are you sure you want to change the base?

Proposed documentation for proposed Model element #39710

Conversation

zachernuk commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

WHATWG/HTML

the Web Platform Tests repository

HTML-ARIA

Uh oh!

zachernuk commented May 27, 2025

Uh oh!

github-actions bot commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Josh-Cena left a comment

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zachernuk commented May 27, 2025 •

edited

Loading

github-actions bot commented May 27, 2025 •

edited

Loading